---
title: 빠른 시작
description: Create your first AI Agent from scratch
---

import { Steps } from '@astrojs/starlight/components';
import { Code } from '@astrojs/starlight/components';
import quickstartExample from '../../../../../../examples/docs/quickstart/index.ts?raw';

## 프로젝트 설정

<Steps>

1. 프로젝트를 생성하고 npm을 초기화합니다. 이 작업은 한 번만 수행하면 됩니다.

   ```bash
   mkdir my_project
   cd my_project
   npm init -y
   ```

2. Agents SDK를 설치합니다.

   ```bash
   npm install @openai/agents zod@3
   ```

3. OpenAI API 키를 설정합니다. 키가 없다면 OpenAI API 키를 생성하려면 [이 지침](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)을 따르세요.

   ```bash
   export OPENAI_API_KEY=sk-...
   ```

   또는 `setDefaultOpenAIKey('<api key>')`를 호출해 프로그램적으로 키를 설정하고,
   트레이싱에는 `setTracingExportApiKey('<api key>')`를 사용할 수 있습니다.
   자세한 내용은 [SDK 설정](/openai-agents-js/ko/guides/config)을 참조하세요.

</Steps>

## 첫 에이전트 생성

에이전트는 instructions와 이름으로 정의합니다.

```typescript
import { Agent } from '@openai/agents';

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});
```

## 첫 에이전트 실행

`run` 메서드를 사용해 에이전트를 실행할 수 있습니다. 시작할 에이전트와 전달할 입력을 함께 넘기면 실행이 트리거됩니다.

이렇게 하면 해당 실행 동안 수행된 최종 출력과 모든 작업이 포함된 결과가 반환됩니다.

```typescript
import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const result = await run(agent, 'When did sharks first appear?');

console.log(result.finalOutput);
```

## 에이전트에 도구 제공

에이전트에 정보를 조회하거나 작업을 수행하는 도구를 부여할 수 있습니다.

```typescript
import { Agent, tool } from '@openai/agents';

const historyFunFact = tool({
  // The name of the tool will be used by the agent to tell what tool to use.
  name: 'history_fun_fact',
  // The description is used to describe **when** to use the tool by telling it **what** it does.
  description: 'Give a fun fact about a historical event',
  // This tool takes no parameters, so we provide an empty Zod Object.
  parameters: z.object({}),
  execute: async () => {
    // The output will be returned back to the Agent to use
    return 'Sharks are older than trees.';
  },
});

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
  // Adding the tool to the agent
  tools: [historyFunFact],
});
```

## 에이전트 추가

추가 에이전트를 유사하게 정의해 문제를 더 작은 부분으로 분해하고, 에이전트가 현재 작업에 더 집중하도록 만들 수 있습니다. 또한 에이전트에 모델을 정의하여 문제마다 다른 모델을 사용할 수 있습니다.

```typescript
const historyTutorAgent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const mathTutorAgent = new Agent({
  name: 'Math Tutor',
  instructions:
    'You provide help with math problems. Explain your reasoning at each step and include examples',
});
```

## 핸드오프 정의

여러 에이전트를 오케스트레이션하기 위해 에이전트에 `handoffs`를 정의할 수 있습니다. 이렇게 하면 에이전트가 다음 에이전트로 대화를 전달할 수 있으며, 이는 실행 과정에서 자동으로 이루어집니다.

```typescript
// Using the Agent.create method to ensures type safety for the final output
const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions:
    "You determine which agent to use based on the user's homework question",
  handoffs: [historyTutorAgent, mathTutorAgent],
});
```

실행이 끝난 후 결과의 `finalAgent` 속성을 보면 어느 에이전트가 최종 응답을 생성했는지 확인할 수 있습니다.

## 에이전트 오케스트레이션 실행

Runner는 개별 에이전트의 실행, 가능한 핸드오프, 도구 실행을 처리합니다.

```typescript
import { run } from '@openai/agents';

async function main() {
  const result = await run(triageAgent, 'What is the capital of France?');
  console.log(result.finalOutput);
}

main().catch((err) => console.error(err));
```

## 모두 합쳐 보기

이제 모두 하나의 전체 예제로 합쳐 봅시다. 이를 `index.js` 파일에 넣고 실행하세요.

<Code lang="typescript" code={quickstartExample} title="빠른 시작" />

## 트레이스 보기

Agents SDK는 자동으로 트레이스를 생성합니다. 이를 통해 에이전트가 어떻게 동작했는지, 어떤 도구를 호출했는지, 어느 에이전트로 핸드오프했는지 검토할 수 있습니다.

에이전트 실행 중에 무엇이 일어났는지 검토하려면
[OpenAI 대시보드의 Trace viewer](https://platform.openai.com/traces)로 이동하세요.

## 다음 단계

더 복잡한 에이전트 플로우를 만드는 방법을 알아보세요.

- [에이전트](/openai-agents-js/ko/guides/agents) 구성에 대해 알아보기
- [에이전트 실행](/openai-agents-js/ko/guides/running-agents)에 대해 알아보기
- [도구](/openai-agents-js/ko/guides/tools), [가드레일](/openai-agents-js/ko/guides/guardrails), [모델](/openai-agents-js/ko/guides/models)에 대해 알아보기
